home *** CD-ROM | disk | FTP | other *** search
/ Whiteline: delta / whiteline CD Series - delta.iso / vision / povray / tools / povquant / animdat / animdat.doc next >
Text File  |  1995-11-25  |  8KB  |  279 lines
  1.                Animdat 1.1         Todd Sankey
  2.  
  3. 1.0  Notice
  4.  
  5. This software is provided as is with no implicit guarantee, blah
  6. blah...
  7.  
  8. In short, its free so use it if you want to. I ask nothing in
  9. return except that you notify me if you find anything wrong or
  10. have any suggested changes. If you feel an overwhelming need to
  11. alleviate the stark nature of my coffers, then any contributions
  12. will be gladly accepted and in return I will notify you of all
  13. future releases.
  14.  
  15.  
  16.      Versions
  17.  
  18. 1.1 : July 22, 1992
  19. Frank van der Hulst added % (mod) operator and ported it to a
  20. Sparcstation. I included his gcc make file.
  21.  
  22. I added gate variables at his suggestion.
  23.  
  24. I added the ability to compile with long scene names. The generated
  25. files are named "root_filename_nnn.dat" where nnn is the scene number.
  26. This is not the default however as for DOS machines it could exceed
  27. the 8 character limit on file names.
  28.  
  29. I improved(?) the documentation after several complaints.
  30. (What do you mean you don't understand, you've got the source
  31. code!)
  32.  
  33. 1.0 : July 2, 1992
  34.  Original release.
  35.  
  36.  
  37. 2.0  Usage guide
  38.  
  39. Animdat allows you to create several files from a template
  40. file and a variable definition file. I use it for creating
  41. animation sequences from a template .DAT file for rendering using
  42. DKBTrace, so I will describe it in this context.
  43.  
  44. Basically Animdat allows you to place variables inside any file.
  45. There are two main classes of variables supported: replacement
  46. variables and gate variables. Variables are identified by a name
  47. which must start with an alphabetic character, can be up to 256
  48. characters in length, and are case sensitive.
  49.  
  50. Variable definitions in the .VAR file must be one definition per
  51. line (although blank lines are permissible) and must
  52. not exceed the maximum line length of 256 characters.
  53.  
  54. Animdat reads and parses the variable definition (.VAR) file and
  55. then processes the template (.DAT) file to create the new files
  56. (scene files).
  57.  
  58.  
  59. 2.1       Defining Variables
  60.  
  61. Variables are defined in the .VAR file. Definitions come in
  62. three flavours: mathematical, file name, and string.
  63.  
  64. 2.1.1               Mathematical Variables
  65.  
  66. A mathematical variable is one whose definition is a correct,
  67. mathematical expression using standard algebraic notation.
  68. The expression can include any legal operators, constant values,
  69. and variable names.
  70.  
  71. The definition of a mathematical variable appears like:
  72.  
  73. var_name = mathematical expression[, initial value]
  74.  
  75. The comma and initial value are optional parameters which give
  76. the variable a predefined value. This allows a variable to be
  77. defined in terms of itself either directly or indirectly.
  78.  
  79. eg.
  80. var_one = var_one + 1.0, 1.0
  81.  
  82. This will create a variable called var_one which will start off
  83. with a value of 1.0 and will increment by 1 for every file
  84. generated.
  85.  
  86. When ANIMDAT encounters a mathematical variable in the .DAT file,
  87. the variable is evaluated and its value (as a double precision
  88. floating point) is placed in the scene file.
  89.  
  90. The supported operators are, in decreasing precedence:
  91.  
  92.      unary -, +, sin, cos, tan, asin, acos, atan, log, exp, rnd
  93.      ^ (exponentiation)
  94.      *, /, % (modulo)
  95.      binary +, -
  96.      <, >, <=, >=, =
  97.  
  98. Precedence can be overridden by using parentheses.
  99.  
  100. Comparison operators (<, >, <=, >=, =) evaluate to a numerical
  101. 1.0 if the condition is true and 0.0 if the condition is false.
  102. So they can be used to produce "multi-definition" variables.
  103.  
  104. eg.
  105. scene = scene + 1.0, 0.0
  106. function = (scene < 10.5) * (1.0)  +  (scene>10.5) * (2.0)
  107.  
  108. Here function will have the value 1.0 for the first 10 scenes and
  109. the value 2.0 for all subsequent scenes.
  110. In evaluating mathematical variables, ANIMDAT first checks if the
  111. variable is dependent on any other variables. If it is, these
  112. variables are updated and evaluated first.
  113.  
  114.  
  115. 2.1.2               Filename Variables
  116.  
  117. Filename variables allow a variable to get its value from another
  118. file. For example, if the values desired are beyond the
  119. capabilities of ANIMDAT's built in functions, they can be
  120. generated externally and placed in another file. Then define the
  121. variable as:
  122.  
  123. var-name2 = #filename
  124.  
  125. Every time the variable is evaluated, the file named is searched
  126. for the next numerical value. The variable then takes on that
  127. value. Filename variables can be used in the definition of
  128. mathematical variables.
  129.  
  130. The named file must contain at least one value for each file
  131. generated. If it does not, its value is undetermined after
  132. running out of values.
  133.  
  134.  
  135. 2.1.3               String Variables
  136.  
  137. String variables replace the variable name in the template file
  138. with a literal string. Their value can not change from one scene
  139. file to the next, so it has only limited use. A string variable
  140. can not be used in the definition of any other variable.
  141.  
  142. A string variable is defined as:
  143.  
  144. var-name3 = "literal string"
  145.  
  146.  
  147. 2.2       Using Variables
  148.  
  149.  
  150. Variables are used in the template (.DAT) file. Currently
  151. variables can be used in 2 main ways: replacement and gating.
  152.  
  153. 2.2.1               Using a Variable as a Replacement Variable
  154.  
  155. Replacement variables are placed in the template (.DAT) file as
  156. @variable_name@. They are identified by the '@' character.
  157.  
  158. In creating the scene files, the variable name
  159. in the .DAT file is replaced by its definition from the .VAR
  160. file after evaluating the variable. The evaluation depends on
  161. how it is defined: mathematical, file name, or string.
  162.  
  163. eg.
  164.  - In the .VAR file -
  165. scene = scene + 1.0, 0
  166.  
  167.  - In the .DAT template file -
  168. This is scene @scene@.
  169.  
  170. This will produce files where in each file @scene@ will be replaced
  171. by the number of the generated file.
  172.  
  173.  
  174.  
  175. 2.2.2               Using a Variable as a Gate Variable
  176.  
  177. Gate variables are used to conditionally include a block of text
  178. in the template file. They appear in the template file as:
  179.  
  180. &variable_name
  181. :
  182. block of text
  183. &
  184.  
  185. The block is started with the '&' character. Immediately
  186. following this with no white space in between is a variable name.
  187. The variable is evaluated and if its value is less than or equal
  188. to 0.0 then the block is NOT included in the generated file. If
  189. its value is greater than 0.0, the block is included in the
  190. generated file.
  191.  
  192. The variable is defined in the .VAR file identically to a
  193. mathematical variable or a filename variable.
  194.  
  195. eg.
  196.  - in the .VAR file -
  197. scene = scene + 1.0, 0.0
  198. gate_var = scene < 10.5
  199.  
  200.  - in the .DAT file -
  201. &gate_var
  202.   some stuff
  203. &
  204.  
  205. The block will be included in the first 10 files generated and in
  206. none of the subsequent files.
  207.  
  208. The block must be terminated by a trailing '&' character. This
  209. terminator must be followed by at least 1 white space character.
  210.  
  211. Blocks can be nested.
  212.  
  213.  
  214.  
  215. 2.3       Predefined Variables
  216.  
  217. ANIMDAT includes three predefined variables: num_scenes,
  218. cur_scene, and x.
  219.  
  220.  
  221. num_scenes appears in the .VAR file and is used to define the
  222. number of files to be generated. Its definition is
  223.  
  224. num_scenes = constant_value
  225.  
  226. Where constant_value is any real number. Since fractional
  227. files are impossible, the value is truncated to the nearest lower
  228. integer. This definition must appear somewhere in the .VAR file
  229. or else an error will occur.
  230.  
  231. cur_scene does not appear in the .VAR file but is simply a
  232. variable provided by ANIMDAT. Its definition is equivalent to:
  233.  
  234. cur_scene = cur_scene + 1.0, 0.0
  235.  
  236. so that it goes from 1 to num_scenes, incrementing by 1 for each
  237. generated file.
  238.  
  239. x is a general-purpose variable that increases monatonically from
  240. 0 to 1. Its equivalent definition is:
  241.  
  242. x = cur_scene/num_scenes
  243.  
  244.  
  245. 2.4       Comments
  246. Comments are allowed in the .VAR file like so: 
  247.  
  248. { comment }.
  249.  
  250. The parser then interprets the comment as a space.
  251.  
  252.  
  253. 2.5       The Command Line
  254.  
  255. The command line for ANIMDAT is:
  256.  
  257. animdat root_filename
  258.  
  259. ANIMDAT then looks for "root_filename.dat" as the template file,
  260. and "root_filename.var" as the variable definition file.
  261.  
  262. 2.6       Examples
  263.  
  264. Enclosed are two files: bball.var and bball.dat. Running:
  265.  
  266.  animdat bball
  267.  
  268. will produce 26 dat files (scene001.dat to scene026.dat) which when
  269. rendered and joined produce a realistic and mathematically
  270. accurate animation of a bouncing ball.
  271.  
  272.  
  273. 3.0  The Author
  274.  
  275. The author can be reached at:
  276.  sankey@unixg.ubc.ca
  277.  
  278.                     Yours truly,
  279.                     Todd Sankey.